The purpose of this article is to provide an overview of the dojo toolkit that is shipped with both the Domino 8.5.1 Server and Notes 8.5.1 Client.
The dojo toolkit version that is shipped with 8.5.1 is Dojo 1.3.2. This version of dojo is fully supported by XPages on both the Domino 8.5.1 Server and the Notes 8.5.1 Client.
This article will explain where to find the corresponding dojo toolkit folder on each of the supported platforms. It will inform you what to do if there are multiple versions of the dojo toolkit installed as part of an upgrade, or indeed, if you want to intentionally install multiple dojo toolkit versions and specify that XPages should use a version other than the default dojo 1.3.2.
The dojo core resources and extensions file structures are described as well as any optimization methods that the user should be aware of.
Finally tips on debugging the dojo toolkit on both the Domino 8.5.1 Server and Notes 8.5.1 Client are discussed.
Dojo Installation and Upgrade
The dojo-1.3.2 toolkit is shipped with the Domino 8.5.1 Server and Notes 8.5.1 Client.
It is installed as part of the installation package on both the Server and the Client.
Server
The dojo-1.3.2 folder is installed to the following location:
\data\domino\js\
Client
The client platform determines where the dojo-1.3.2 toolkit is installed.
On the Windows Platform, the dojo-1.3.2 toolkit is installed to the following location:
\data\domino\js\
On the Mac Client, the dojo-1.3.2 toolkit is installed to the following location:
/Application/Notes.app/Contents/resources/English.lproj/Data/domino/js/
On the Linux Platform, the dojo-1.3.2 toolkit is installed to the following location:
/opt/ibm/lotus/notes/data/shared/domino/js/
Multiple Dojo Versions
These locations can contain more than one dojo version.
Where a clean installation of either the Domino Server or Notes Client is performed, the Dojo 1.3.2 toolkit will be installed to the corresponding location.
Upgrading an existing Domino Server, however, will continue to preserve any pre-existing versions of dojo along with the newly installed dojo-1.3.2 version.
Upgrading a Domino 8.5 Server to 8.5.1, will thus contain both the pre-existing dojo-1.1.1 folder, which was installed as part of the Domino 8.5 Server, and dojo-1.3.2 which is installed as part of Domino 8.5.1 Server.
Note : While any pre-existing versions of dojo which reside in these locations will not be deleted, only dojo-1.3.2, which comes installed as part of the Domino 8.5.1 Server and Notes 8.5.1 Client, is fully supported by XPages.
XPages will automatically pick up the latest dojo version that exists in this location.
These older dojo versions are primarily retained in order to allow users to port any changes they may have made to older versions of dojo, thus retaining any pre-existing functionality.
Older versions of dojo can be removed from this location, however dojo-1.3.2 should
never be deleted.
Newer versions of dojo can also be manually added to these locations. However as stated previously, any new versions are not fully supported by XPages, and thus this not recommended without being fully tested by the user for compatibility.
When adding newer versions of dojo please note, XPages will
always pick up the newest version of dojo.
Specific versions of Dojo in
xsp.properties
When there are multiple versions of dojo installed, XPages will always use the latest version of dojo contained in the Domino Server or Notes Client.
A user can define a specific dojo version that an XPage is to use, by modifying a property in the xsp.properties file.
Please note, specifying a dojo version other than the default dojo-1.3.2 is not fully supported and will require additional compatibility testing.
Rename the xsp.properties.sample file to xsp.properties and open it.
This file is located in the Domino 8.5.1 Server install, at the location
\data\properties
or the Lotus 8.5.1 Client install
, at the location
\data\properties
Uncomment and modify the following property in the xsp.properties file
xsp.client.script.dojo.version =
For example:
xsp.client.script.dojo.version = 1.3.2
The dojo version specified here will be the version of dojo that XPages will use on the Domino 8.5.1 Server or Notes 8.5.1 Client, depending on whether this setting is modified on the Server xsp.properties file or the Client xsp.properties file.
To revert back to the default version of dojo, comment out this property.
File Structure
The dojo-1.3.2 directory has a similar layout to the dojo-1.1.1 directory available with the Domino 8.5 server.
The dojo resources available in the dojo toolkit are as follows:
....\dojo-1.3.2\dojo - the core dojo classes
....\dojo-1.3.2\dijit - dojo UI components (dijits)
....\dojo-1.3.2\dojox - extended dojo classes
....\dojo-1.3.2\ibm - IBM classes used by XPages and classic web rendering
The dojo-1.3.2\ibm\xsp\widget\layout directory contains the XPage extensions of the dojo toolkit.
All dojo files are compressed and optimized to ensure good performance. In additon, dojo layers are used to minimize the number of files downloaded per HTTP request. Dojo layers group together related dojo modules into one big JavaScript file which loads much faster than the individual JavaScript modules it contains. They can be generated through a custom Dojo build.
Debugging and Examining XPage Functionality
Within the dojo-1.3.2\ibm\xsp\widget\layout directory, 3 different versions of each file are available:
- The gzipped file (.gz)
- The JavaScript source file (.js)
- The uncompressed JavaScript file (uncompressed.js)
The gzipped file (.gz) is the smallest and is used for XPages in the Notes Client and on the Web. If the user's Web Browser does not support gzipped file types, the JavaScript source file (.js), which is a compressed version of the source code, is used. This is a behaviour coming from the Domino Web Server.
The uncompressed JavaScript file (uncompressed.js) is a more readable version of the source code and is available for debugging purposes.
In order to debug one of the client side libraries, you have 2 options:
- Remove the .gz and .js files from the directory and rename the uncompressed.js file to .js.
- Create a Web Site Rule on the server in which you substitute incoming requests with a pattern of */ibm/*.js by a replacement pattern of */ibm/*.js.uncompressed.js
Restart the HTTP task after you have created the rule.
With both methods ensure to delete the browser cache to ensure the correct version of the .js file is loaded.
This allows you to see more clearly the implementation details and to determine the cause of any unexpected behaviour in an XPage.
Note: If you follow these steps to use the contents of the uncompressed.js files at runtime, dojo layers will no longer be used and a HTTP request for any XPage that requires dojo resources will result in many more files being loaded.
In order to debug dojo resources, web browser development tools prove invaluable.
Firebug which can be installed as an add-on in Mozilla Firefox, is particularly beneficial.
Developer toolbars are also available for other browsers and can prove useful.
In order to debug an XPage application within the Notes Client, there is a property available in the xsp.properties file which will enable Firebug Lite in Notes.
To leverage this functionality, uncomment and modify the following property in xsp.properties
xsp.client.script.dojo.djConfig=isDebug:true
This will provide a certain amount of support for debugging dojo within the Notes Client itself.
If any more advanced debugging is required, you should replicate the XPages application to the Domino Server, if possible, and avail of the complete Firebug tool within Mozilla Firefox.
Further debugging options are also available, for example,
xsp.client.script.dojo.djConfig=debugAtAllCosts:true
For more information and full details of these options, please see
The Dojo Debugging Tutorial.
Details regarding the functionality provided in the XSPClientDojo JavaScript library are available in the article
Client Side JavaScript Libraries in XPages
Summary
You should now have a basic overview of the Dojo 1.3.2 toolkit which is installed as part of the Domino 8.5.1 Server and Notes 8.5.1 Client. In particular, you have learned what actually gets installed as part of the installation or upgrade and where to find the dojo toolkit along with its resources and extensions.
This article has also discussed useful properties in the xsp.properties file which can be used to specify particular dojo versions and to debug XPages in the Notes Client. Finally, some tips for debugging the dojo toolkit on both the Server and the Client are provided.